home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Database Designers / Rational Rose 2000 / Rational Setup.EXE / common / lib / Win32 / NetResource.pm < prev    next >
Text File  |  1998-11-15  |  9KB  |  334 lines
  1. package Win32::NetResource;
  2.  
  3. require Exporter;
  4. require DynaLoader;
  5. require AutoLoader;
  6.  
  7. $VERSION = '0.03';
  8.  
  9. @ISA = qw(Exporter DynaLoader);
  10. # Items to export into callers namespace by default. Note: do not export
  11. # names by default without a very good reason. Use EXPORT_OK instead.
  12. # Do not simply export all your public functions/methods/constants.
  13. @EXPORT = qw(
  14.     RESOURCEDISPLAYTYPE_DOMAIN
  15.     RESOURCEDISPLAYTYPE_FILE
  16.     RESOURCEDISPLAYTYPE_GENERIC
  17.     RESOURCEDISPLAYTYPE_GROUP
  18.     RESOURCEDISPLAYTYPE_SERVER
  19.     RESOURCEDISPLAYTYPE_SHARE
  20.     RESOURCEDISPLAYTYPE_TREE
  21.     RESOURCETYPE_ANY
  22.     RESOURCETYPE_DISK
  23.     RESOURCETYPE_PRINT
  24.     RESOURCETYPE_UNKNOWN
  25.     RESOURCEUSAGE_CONNECTABLE
  26.     RESOURCEUSAGE_CONTAINER
  27.     RESOURCEUSAGE_RESERVED
  28.     RESOURCE_CONNECTED
  29.     RESOURCE_GLOBALNET
  30.     RESOURCE_REMEMBERED
  31. );
  32.  
  33. =head1 NAME
  34.  
  35. Win32::NetResource - manage network resources in perl
  36.  
  37. =head1 SYNOPSIS
  38.  
  39.     use Win32::NetResource;
  40.  
  41.     $ShareInfo = {
  42.                     'path' => "C:\\MyShareDir",
  43.                     'netname' => "MyShare",
  44.                     'remark' => "It is good to share",
  45.                     'passwd' => "",
  46.                     'current-users' =>0,
  47.                     'permissions' => 0,
  48.                     'maxusers' => -1,
  49.                     'type'  => 0,
  50.                     };
  51.     
  52.     Win32::NetResource::NetShareAdd( $ShareInfo,$parm )
  53.         or die "unable to add share";
  54.  
  55.  
  56. =head1 DESCRIPTION
  57.  
  58. This module offers control over the network resources of Win32.Disks,
  59. printers etc can be shared over a network.
  60.  
  61. =head1 DATA TYPES
  62.  
  63. There are two main data types required to control network resources.
  64. In Perl these are represented by hash types.
  65.  
  66. =over 10
  67.  
  68. =item %NETRESOURCE
  69.  
  70.         KEY                    VALUE
  71.         
  72.         'Scope'         =>  Scope of an Enumeration
  73.                             RESOURCE_CONNECTED,
  74.                             RESOURCE_GLOBALNET,
  75.                             RESOURCE_REMEMBERED.
  76.         
  77.         'Type'          =>  The type of resource to Enum
  78.                             RESOURCETYPE_ANY    All resources
  79.                             RESOURCETYPE_DISK    Disk resources
  80.                             RESOURCETYPE_PRINT    Print resources
  81.         
  82.         'DisplayType'   =>  The way the resource should be displayed.
  83.                             RESOURCEDISPLAYTYPE_DOMAIN    
  84.                             The object should be displayed as a domain.
  85.                             RESOURCEDISPLAYTYPE_GENERIC    
  86.                             The method used to display the object does not matter.
  87.                             RESOURCEDISPLAYTYPE_SERVER    
  88.                             The object should be displayed as a server.
  89.                             RESOURCEDISPLAYTYPE_SHARE    
  90.                             The object should be displayed as a sharepoint.
  91.         
  92.         'Usage'         =>  Specifies the Resources usage:
  93.                             RESOURCEUSAGE_CONNECTABLE
  94.                             RESOURCEUSAGE_CONTAINER.
  95.         
  96.         'LocalName'     =>  Name of the local device the resource is 
  97.                             connected to.
  98.         
  99.         'RemoteName'    =>  The network name of the resource.
  100.         
  101.         'Comment'       =>  A string comment.
  102.         
  103.         'Provider'      =>  Name of the provider of the resource.
  104.  
  105. =back    
  106.  
  107. =item %SHARE_INFO
  108.  
  109. This hash represents the SHARE_INFO_502 struct.
  110.  
  111. =over 10
  112.  
  113.         KEY                    VALUE
  114.         'netname'        =>    Name of the share.
  115.         'type'           =>    type of share.
  116.         'remark'         =>    A string comment.
  117.         'permissions'    =>    Permissions value
  118.         'maxusers'       =>    the max # of users.
  119.         'current-users'  =>    the current # of users.
  120.         'path'           =>    The path of the share.
  121.         'passwd'         =>    A password if one is req'd
  122.  
  123. =back
  124.  
  125. =head1 FUNCTIONS
  126.  
  127. =head2 NOTE
  128.  
  129. All of the functions return FALSE (0) if they fail.
  130.  
  131. =over 10
  132.  
  133. =item GetSharedResources(\@Resources,dwType)
  134.  
  135. Creates a list in @Resources of %NETRESOURCE hash references.
  136.  
  137. =item AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)
  138.  
  139. Makes a connection to a network resource specified by %NETRESOURCE
  140.  
  141. =item CancelConnection($Name,$Connection,$Force)
  142.  
  143. Cancels a connection to a network resource connected to local device 
  144. $name.$Connection is either 1 - persistent connection or 0, non-persistent.
  145.  
  146. =item WNetGetLastError($ErrorCode,$Description,$Name)
  147.  
  148. Gets the Extended Network Error.
  149.  
  150. =item GetError( $ErrorCode )
  151.  
  152. Gets the last Error for a Win32::NetResource call.
  153.  
  154. =item GetUNCName( $UNCName, $LocalPath );
  155.  
  156. Returns the UNC name of the disk share connected to $LocalPath in $UNCName.
  157.  
  158. =head2 NOTE
  159.  
  160. $servername is optional for all the calls below. (if not given the
  161. local machine is assumed.)
  162.  
  163. =item NetShareAdd(\%SHARE,$parm_err,$servername = NULL )
  164.  
  165. Add a share for sharing.
  166.  
  167. =item NetShareCheck($device,$type,$servername = NULL )
  168.  
  169. Check if a share is available for connection.
  170.  
  171. =item NetShareDel( $netname, $servername = NULL )
  172.  
  173. Remove a share from a machines list of shares.
  174.  
  175. =item NetShareGetInfo( $netname, \%SHARE,$servername=NULL )
  176.  
  177. Get the %SHARE_INFO information about the share $netname on the
  178. server $servername.
  179.  
  180. =item NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)
  181.  
  182. Set the information for share $netname.
  183.  
  184. =item AUTHOR
  185.  
  186. Jesse Dougherty for Hip Communications.
  187. Gurusamy Sarathy <gsar@umich.edu> had to clean up the horrendous code
  188. and the bugs.
  189.  
  190. =back
  191.  
  192. =cut
  193.  
  194. sub AUTOLOAD {
  195.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  196.     # XS function.  If a constant is not found then control is passed
  197.     # to the AUTOLOAD in AutoLoader.
  198.  
  199.     my($constname);
  200.     ($constname = $AUTOLOAD) =~ s/.*:://;
  201.     #reset $! to zero to reset any current errors.
  202.     $!=0;
  203.     my $val = constant($constname, @_ ? $_[0] : 0);
  204.     if ($! != 0) {
  205.         if ($! =~ /Invalid/) {
  206.             $AutoLoader::AUTOLOAD = $AUTOLOAD;
  207.             goto &AutoLoader::AUTOLOAD;
  208.         }
  209.         else {
  210.             ($pack,$file,$line) = caller;
  211.             die "Your vendor has not defined Win32::NetResource macro $constname, used at $file line $line.
  212. ";
  213.         }
  214.     }
  215.     eval "sub $AUTOLOAD { $val }";
  216.     goto &$AUTOLOAD;
  217. }
  218.  
  219. sub AddConnection
  220. {
  221.     my $h = $_[0];
  222.     die "AddConnection: HASH reference required" unless ref($h) eq "HASH";
  223.  
  224.     #
  225.     # The last four items *must* not be deallocated until the
  226.     # _AddConnection() completes (since the packed structure is
  227.     # pointing into these values.
  228.     #
  229.     my $netres = pack( 'i4 p4', $h->{Scope},
  230.                     $h->{Type},
  231.                 $h->{DisplayType},
  232.                 $h->{Usage},
  233.                 $h->{LocalName},
  234.                 $h->{RemoteName},
  235.                 $h->{Comment},
  236.                 $h->{Provider});
  237.     _AddConnection($netres,$_[1],$_[2],$_[3]);
  238. }
  239.  
  240. #use Data::Dumper;
  241.  
  242. sub GetSharedResources
  243. {
  244.     die "GetSharedResources: ARRAY reference required"
  245.     unless ref($_[0]) eq "ARRAY";
  246.  
  247.     my $aref = [];
  248.  
  249.     # Get the shared resources.
  250.  
  251.     my $ret = _GetSharedResources( $aref ,$_[1] );
  252.     
  253.     # build the array of hashes in $_[0]
  254. #   print Dumper($aref);    
  255.     if ($ret) {
  256.     foreach ( @$aref ) {
  257.         my %hash;
  258.         @hash{'Scope',
  259.           'Type',
  260.           'DisplayType',
  261.           'Usage',
  262.           'LocalName',
  263.           'RemoteName',
  264.           'Comment',
  265.           'Provider'} = split /\001/, $_;
  266.         push @{$_[0]}, \%hash;
  267.     }
  268.     }
  269.  
  270.     $ret;
  271. }
  272.  
  273. sub NetShareAdd
  274. {
  275.     my $shareinfo = _hash2SHARE( $_[0] );
  276.     _NetShareAdd($shareinfo,$_[1], $_[2] || "");
  277. }
  278.  
  279. sub NetShareGetInfo
  280. {
  281.     my ($netinfo,$val);
  282.     $val = _NetShareGetInfo( $_[0],$netinfo,$_[2] || "");
  283.     $_[1] = _SHARE2hash( $netinfo );    
  284.     $val;
  285. }
  286.  
  287. sub NetShareSetInfo
  288. {
  289.     my $shareinfo = _hash2SHARE( $_[1] );
  290.     _NetShareSetInfo( $_[0],$shareinfo,$_[2],$_[3] || "");
  291. }
  292.  
  293.  
  294. # These are private functions to work with the ShareInfo structure.
  295. # please note that the implementation of these calls requires the
  296. # SHARE_INFO_502 level of information.
  297.  
  298. sub _SHARE2hash
  299. {
  300.     my %hash = ();
  301.     @hash{'type',
  302.           'permissions',
  303.           'maxusers',
  304.           'current-users',
  305.           'remark',
  306.           'netname',
  307.           'path',
  308.           'passwd'} = unpack('i4 A257 A81 A257 A257',$_[0]);
  309.  
  310.     return \%hash;
  311. }
  312.  
  313. sub _hash2SHARE
  314. {
  315.     my $h = $_[0];
  316.     die "Argument must be a HASH reference" unless ref($h) eq "HASH";
  317.  
  318.     return pack 'i4 a257 a81 a257 a257',
  319.          @$h{'type',
  320.             'permissions',
  321.             'maxusers',
  322.             'current-users',
  323.             'remark',
  324.             'netname',
  325.             'path',
  326.             'passwd'};
  327. }
  328.  
  329.  
  330. bootstrap Win32::NetResource;
  331.  
  332. 1;
  333. __END__
  334.